Plugin adds the s3upload method to the common io.File class, you can call this method passing a simple closure configuring the upload request or even with no parameters to upload the file following the application config.All these properties will be described in the next topic of this guide.Using default plugin configuration
def s3file = new File("test.txt").s3upload()Configuring per upload
def s3file = new File("test.txt").s3upload {
bucket "xxx"
path "test/files/"
//more config options
}Bucket name
To set a default bucket, that will be used to all file upload use the config belowgrails {
plugin {
aws {
s3 {
bucket = "grails-plugin-test"
}
}
}
}ACL (file permission)
The permissions that will be granted on this file, you can use:
- public: Allow public access to everyone that attemps to read this file
- private: Sets private access to this file, only your account will read/write on it
- public_read_write: This will make this file wide open to any AWS account, read and write
- authenticated_read: Using this acl string, only logged AWS accounts will have permissions to read the file
To configure public access as default to all file uploads, use this:grails {
plugin {
aws {
s3 {
acl = "public"
}
}
}
}grails {
plugin {
aws {
s3 {
acl = "private"
}
}
}
}RRS - Reduced Redundancy Storage
RRS stored files provides a cheaper storage with 99.99% durability instead of 99.999999999% as the default provided by AWS S3. More information here: http://aws.amazon.com/about-aws/whats-new/2010/05/19/announcing-amazon-s3-reduced-redundancy-storage/This is disabled by default, if you like to set RRS enabled for all uploads, use this config key:grails {
plugin {
aws {
s3 {
rrs = true
}
}
}
}package grails.plugin.aws.s3
import org.jets3t.service.model.S3Objectclass S3File { @Delegate S3Object source public S3File(S3Object _source) {
this.source = _source
}
}def s3file = … //upload the file
def etag = s3file.getETag()
Simple File upload
def s3file = new File("/tmp/test.txt").s3upload {
path "folder/to/my/file/"
}<default-bucket>.s3.amazonaws.com/folder/to/my/file/test.txt
Storing file information for later retrieval
If you are uploading some picture to S3, you'll probably need to store information on how to get that file again later.
The S3File object returned will give all information you'll need. Now, depends on what information you want to store. Follow S3Object docs (link above) and get whatever you want.A common approach would be storing the bucket, path and file (key). With these parameters you can rebuild the URL to reach the file, or even build another S3Object to delete it. Some next version of this plugin will allow s3file deletion. S3 does not support paths or buckets inside other buckets, to solve this and keep your files organized, you can use the path method inside the config closure. Doing this, the plugin will set a metadata into this file telling AWS that this file is virtually in a folder that does not exist.The effect is exactly like in a regular folder. For example, doing the upload below:def uploadedFile = new File("/tmp/profile-picture.jpg").s3upload {
bucket "my-aws-app"
path "pictures/user/profile/"
}http://my-aws-app.s3.amazonaws.com/pictures/user/profile/profile-picture.jpg
def uploadedFile = new File("/tmp/test.txt").s3upload {
credentials "my-other-access-key", "my-other-secret-key"
}def uploadedFile = new File("/tmp/test.txt").s3upload {
bucket "other-bucket"
}other-bucket.s3.amazonaws.com/test.txt
def uploadedFile = new File("/tmp/test.txt").s3upload {
bucket "bucket-not-yet-created-in-europe", "EU"
}def uploadedFile = new File("/tmp/test.txt").s3upload {
acl "private"
}def uploadedFile = new File("/tmp/test.txt").s3upload {
rrs false
}def uploadedFile = new File("/tmp/test.txt").s3upload {
metadata [user-id: 123, username: 'johndoe', registered-date: new Date().format('dd/MM/yyyy')]
}def s3file = new File("test.txt").s3upload {
bucket "secret-files"
acl "private"
}def s3file = new File("test.txt").s3upload {
bucket "secret-files"
acl "private"
}def publicUrl = s3file.publicUrlFor()Defining when public URL will expire
You can set the expires date for the public URL, passing an argument to publicUrlFor method.s3file.publicUrlFor(3.hours) //will be available for 3 hours
s3file.publicUrlFor(10.years) //available for 10 years
s3file.publicUrlFor(1.second) //you won't get this one on time
1.second or 2.seconds
1.minute or 2.minutes
1.hour or 2.hours
1.day or 2.days
1.month or 2.months
1.year or 2.years
def s3file = new File("test.txt").s3upload {
bucket "secret-files"
acl "private"
}def torrentUrl = s3file.torrent()